Inside Macintosh: QuickTime Components

Previous | Chapter Top | Chapter Contents | Next

Specifying a Test Image

The standard image-compression dialog component provided by Apple supports a test image. As you can see in Figure 3 , the dialog box contains a small image along with the other parts of the dialog box. The component uses this image to display the effect of the user's image-compression settings. In this manner, the user can experiment with different settings and see the results of those settings immediately.

The component provides three functions that allow you to specify the test image. Use the SCSetTestImagePictHandle function if your test image is stored in a handle. Use the SCSetTestImagePictFile function if your test image is in a picture file. The SCSetTestImagePixMap function sets the test image from a pixel map.

SCSetTestImagePictHandle

The SCSetTestImagePictHandle function sets the dialog box's test image from a picture that is stored in a handle.

pascal ComponentResult SCSetTestImagePictHandle
                                         (ComponentInstance ci, PicHandle testPict,
                                          Rect *testRect, short testFlags);
ci
Identifies your application's connection to a standard image-compression dialog component.
testPict
Identifies a handle that contains the new test image. Your application is responsible for disposing of this handle when you are done with it. You must clear the image or close your connection to the standard image-compression dialog component before you dispose of this handle or close the corresponding resource file. You must set this handle as nonpurgeable.
Set this parameter to nil to clear the test image.
testRect
Contains a pointer to a rectangle structure. This rectangle specifies, in the coordinate system of the source image, the area of interest or point of interest in the test image. The area of interest defines a portion of the test image that is to be shown to the user in the dialog box. Use this parameter to direct the component to a specific portion of the test image. The component uses the value of the testFlags parameter to determine how it transforms this image before displaying it to the user. The component uses the testFlags parameter only when the test image is larger than the test image portion of the dialog box.
You may specify a point of interest by setting the points in the rectangle structure so that they enclose a single point--for example, (0,0) and (1,1). The component centers this point in the image that is displayed in the dialog box, and displays the part of the image that fits in the test image portion of the dialog box.
To use the entire picture, specify nil in this parameter.
testFlags
Specifies how the component is to display a test image that is larger than the test image portion of the dialog box. If you set this parameter to 0, the component uses a default method of its own choosing. In all cases, the component centers the area or point of interest in the test image portion of the dialog box, and then displays some part of the test image.
You may indicate your display preference by setting this parameter to one of the following values:
scPreferCropping
Indicates that the component should crop the test image to fit the test image portion of the dialog box. The component displays the part of the image that fits in the test image portion of the box. If the image is smaller than the space allotted in the dialog box, the component does not alter the image before displaying it--the resulting image is smaller than the available space.
scPreferScaling
Indicates that the component should scale the test image to fit the test image portion of the dialog box. The component shrinks the image to fit the test image portion of the dialog box.
scPreferScalingAndCropping
Indicates that the component should both scale and crop the test image. This option is useful with very large test images. The component first shrinks the image to approximately the size of the test image portion of the dialog box, and then trims the image so that it fits the available space.

RESULT CODE

paramErr

-50

Invalid parameter specified

SCSetTestImagePictFile

The SCSetTestImagePictFile function sets the dialog box's test image from a picture that is stored in a picture file.

pascal ComponentResult SCSetTestImagePictFile
                                         (ComponentInstance ci, short testFileRef,
                                         Rect *testRect, short testFlags);
ci
Identifies your application's connection to a standard image-compression dialog component.
testFileRef
Identifies the file that contains the new test image. Your application is responsible for opening this file before calling this function. You must also close the file when you are done with it. You must clear the image or close your connection to the standard image-compression dialog component before you close the file. If the file contains a large image, the component may take some time to display the standard image-compression dialog box. In this case, the component displays the watch cursor while it loads the test image.
Set this parameter to 0 to clear the test image.
testRect
Contains a pointer to a rectangle structure. This rectangle specifies, in the coordinate system of the source image, the area of interest or point of interest in the test image. The area of interest defines a portion of the test image that is to be shown to the user in the dialog box. Use this parameter to direct the component to a specific portion of the test image. The component uses the value of the testFlags parameter to determine how it transforms large images before displaying them to the user.
You may specify a point of interest by setting the points in the rectangle structure so that they enclose a single point--for example, (0,0) and (1,1). The component centers this point in the image that is displayed in the dialog box, and displays the part of the image that fits in the test image portion of the dialog box.
To use the entire picture file, pass nil in this parameter.
testFlags
Specifies how the component is to display a test image that is larger than the test image portion of the dialog box. If you set this parameter to 0, the component uses a default method of its own choosing. In all cases, the component centers the area or point of interest in the test image portion of the dialog box, and then displays some part of the test image.
You may indicate your display preference by setting this parameter to one of the following values:
scPreferCropping
Indicates that the component should crop the test image to fit the test image portion of the dialog box. The component displays the part of the image that fits in the test image portion of the box. If the image is smaller than the space alloted in the dialog box, the component does not alter the image before displaying it--the resulting image is smaller than the available space.
scPreferScaling
Indicates that the component should scale the test image to fit the test image portion of the dialog box. The component shrinks the image to fit the test image portion of the dialog box.
scPreferScalingAndCropping
Indicates that the component should both scale and crop the test image. This option is useful with very large test images. The component first shrinks the image to approximately the size of the test image portion of the dialog box, then trims the image so that it fits the available space.

RESULT CODES

paramErr

-50

Invalid parameter specified

File Manager errors

SCSetTestImagePixMap

The SCSetTestImagePixMap function sets the dialog box's test image from a picture that is stored in a pixel map.

pascal ComponentResult SCSetTestImagePixMap (ComponentInstance ci,
                                         PixMapHandle testPixMap,
                                         Rect *testRect,
                                         short testFlags);
ci
Identifies your application's connection to a standard image-compression dialog component.
testPixMap
Contains a handle to a pixel map that contains the new test image. Your application is responsible for creating this pixel map before calling this function. You must also dispose of the pixel map when you are done with it. You must clear the image or close your connection to the standard image-compression dialog component before you dispose of the pixel map.
Set this parameter to nil to clear the test image.
testRect
Contains a pointer to a rectangle structure. This rectangle specifies, in the coordinate system of the source image, the area of interest or point of interest in the test image. The area of interest defines a portion of the test image that is to be shown to the user in the dialog box. Use this parameter to direct the component to a specific portion of the test image. The component uses the value of the testFlags parameter to determine how it transforms large images before displaying them to the user.
You may specify a point of interest by setting the points in the rectangle structure so that they enclose a single point--for example, (0,0) and (1,1). The component centers this point in the image that is displayed in the dialog box, and displays the part of the image that fits in the test image portion of the dialog box.
To use the entire pixel map, specify nil in this parameter.
testFlags
Specifies how the component is to display a test image that is larger than the test image portion of the dialog box. If you set this parameter to 0, the component uses a default method of its own choosing. In all cases, the component centers the area or point of interest in the test image portion of the dialog box, and then displays some part of the test image.
You may indicate your display preference by setting this parameter to one of the following values:
scPreferCropping
Indicates that the component should crop the test image to fit the test image portion of the dialog box. The component displays the part of the image that fits in the test image portion of the box. If the image is smaller than the space alloted in the dialog box, the component does not alter the image before displaying it--the resulting image is smaller than the available space.
scPreferScaling
Indicates that the component should scale the test image to fit the test image portion of the dialog box. The component shrinks the image to fit the test image portion of the dialog box.
scPreferScalingAndCropping
Indicates that the component should both scale and crop the test image. This option is useful with very large test images. The component first shrinks the image to approximately the size of the test image portion of the dialog box, then trims the image so that it fits the available space.

RESULT CODE

paramErr

-50

Invalid parameter specified

© 1997 Apple Computer, Inc.

Previous | Chapter Top | Chapter Contents | Next